                         Fill Box With Spheres
                             Version 1.0.0

Syntax:

FBWS (cantainer_width, cantainer_height, cantainer_depth, number_of_spheres,
      sphere_max_radius, sphere_min_radius, intersect, contain_all)

Description:

This macro fills a box with a certain number of randomly placed spheres.
The spheres can be of random size, between a min and a max values.
The spheres can intersect each other or can be placed carefully to avoid
intersections.
See the file "example.pov" for an example of FBWS usage.

Options:

cantainer_width:
cantainer_height:
cantainer_depth: respectively the X, Y and Z dimensions of the box.
Note that it is centered in the origin.
You can then translate and rotate wherever you want.

number_of_spheres: the number of spheres to fill with. As you can guess the
larger this number the longer parsing and rendering times.
Minimum value is "1".
NOTE: if "intersect" option is set to "no" you should keep this number low and
than increase it gradually. If you fill a small box with too much of spheres
(or of pretty big radius), POV-Ray will never end the parsing fase since FBSW
will search in eternity for a sphere that fit in the box (and this can be impossible).
After some trial and error you will discover an optimal value.

sphere_max_radius: this is the maximum radius that the randomly generated
sphere size can have.
It cannot be lower than "sphere_min_radius".
NOTE: to fill a box with spheres of the same radius simply set
"sphere_max_radius" and "sphere_min_radius" to the same value.

sphere_min_radius: this is the maximum radius that the randomly generated
sphere size can have.
It must be a positive value.

intersect: set this option to "yes" if you want to allow the spheres to
intersecate.
Set it to "no" if you want the sphere to be place in a way to avoid
intersections (the surfaces of the spheres can "touch", however).
NOTE: use the "no" option carefully since it may dramatically increase parsing
time (the parsing time may became infinite, see the NOTE of "number_of_spheres").

contain_all: set this option to "yes" if you want the sphere to be completly
contained between box boundaries.
Set it to "no" if you want that only the center of the spheres is contained
between box boundaries.

Known Problems:

- There is no way (known to me) to avoid POV-Ray to engage a infinite loop during
parsing if the "intersect" option is set to "no" and FBWS is not able to find
a sphere that fit the box without intersect any other sphere. Read the NOTE of
"number_of_spheres" option to avoid the problem.
- The spheres are placed randomly, regardless of box proportions. This means
that if the box has one of the dimensions much larger than the other two, the
sphere will not appear uniformly placed but somewath "streched".
I'm working to get a better algorithm.

Version history:

1.0.0 (6/November/1998)
Initial release.


Legal note:

FBWS is freeware and you can use it freely. It can be distribuited in any
way but only if this readme is provided.
However is not public domain and remains propierty of the author.
Modified versions of the macro can be distribuited but a note regarding
the author of the original one is greatly appreciated.


I would thank all the POV Team for their efforts and to bring us the macros
wich are just a marvelous dream (and I won't wake up!)  :)
Comments, suggestions, and ideas for future macros are encouraged.

Diego Krota

e-mail:    dkrota@geocities.com (if this address may be no longer valid in future
go to my Home Page and you will find the new address)

Home Page: http://www.geocities.com/SiliconValley/Way/2419

POV-Ray Macros: http://www.geocities.com/SiliconValley/Way/2419/POVMacros.html
